home *** CD-ROM | disk | FTP | other *** search
/ Turnbull China Bikeride / Turnbull China Bikeride - Disc 2.iso / STUTTGART / LANG / C / LIB / GSTREAM / Docs next >
Text File  |  1993-05-08  |  3KB  |  86 lines
  1. The code may be freely distributed as long as the copyright message and
  2. conditions are kept with each file.  Anyone who likes it please feel
  3. free to send me some money (>=10).  You will recieve a disk with the
  4. latest version of gstream - and any new stream types I've made.
  5.  
  6. Note: these files are NOT Public Domain, as I retain copyright.
  7.  
  8. Disclaimer:
  9. -----------
  10.  
  11. This code is supplied in good faith, but not liability can be accepted
  12. for loss incurred through the use or inability to use this code.
  13.  
  14. Author:
  15. -------
  16. Simon Proven
  17. email: sproven@cs.strath.ac.uk
  18. snail mail: Castle Cottage,
  19.             Portencross,
  20.             West Kilbride,
  21.             KA23 9QA
  22.             SCOTLAND
  23.  
  24.  
  25. Docs
  26. ----
  27.  
  28. gstream provides a uniform means of communicating with various devices
  29. or applications in RISC OS.  It provides a range of functions similar
  30. to the stdio functions (eg fprintf == gsprintf ).  However, streams are
  31. opened differently - via a number of bolt on extensions which implement
  32. the low level access to a given type of stream.  This makes it possible
  33. for users of gstream to add their own types of stream without needing
  34. to make any changes to gstream itself.  This is advantageous in that
  35. the gstream code will not get hacked up by a million different people,
  36. which would make updates to newer versions very difficult.
  37.  
  38. Most of the functions exported by gstream can be understood by looking
  39. at their stdio equivalents - where differences occur these are
  40. documented in the sources.  It is hoped that these differences will be
  41. removed when I can be bothered.
  42.  
  43. The only other functions which need explaining to the user of gstream
  44. are:
  45.  
  46. gsopeninternalw
  47. gsopeninternalr
  48. gsdiscardinternal
  49. gsgetbuf
  50.  
  51. The first three of these provide a means to hold data in flex blocks. 
  52. The system is write once, read many - ie you first of all open a flex
  53. block to write to with gsopeninternalw, write your data to it, then
  54. gsclose it.  Then, you can open the same stream with gsopeninternalr
  55. and read the data back, then gsclose it.  If you then use
  56. gsopeninternalr again will be able to read the data back again.
  57.  
  58. gsdiscardinternal frees the memory used by the internal stream, ready
  59. losing the data.  After it has been called you can then call
  60. gsopeninternalw again.
  61.  
  62. gsgetbuf is a function which tries to claim a flex block between
  63. minsize and maxsize bytes in size, returing the size of block claimed
  64. (0 if no block was claimed).  See examples of its use in gstream,
  65. osstream and ramstream.
  66.  
  67. The rest should be fairly self-explanatory.  To see how to create your
  68. own stream types, look at osstream, ramstream and xferstream, and the
  69. example below.
  70.  
  71. Things to do
  72. ------------
  73.  
  74. * Add stream types for Acorn's Cut/Copy/Paste protocol
  75.  
  76. * Add stream types to handle RISC OS 3 pipes - so that a m/tasking app
  77.   can not only write to a pipe but also read from one without hanging.
  78.  
  79. * Add stream types to write to screen and read from keyboard.  If in
  80.   m/tasking app, these stream types will open a window on the screen for
  81.   I/O.  Suggestions wanted.
  82.  
  83. * Try to allow saving back to sending task (currently won't work - has
  84.   to be trapped by xferrecv to avoid crash)
  85.  
  86.